Commands and Parameters
Run
You usually don’t need to describe ‘run’ commands for application in your scripts because AppleScript sends an implicit ‘run’ command to an application that is not already running when a script uses the application. The ‘run’ command is called ‘open application’ event in Apple event terms and it is originally supposed to be used by the Finder when it opens an application.*
In many cases, also in QuoEdit, when an application receives a ‘run’ command (‘open application’ event), it makes a new untitled document window.
As an exception in QuoEdit, if some modifier keys are held down while handling the ‘open application’ event, one of launch options can be applied. See “Options at the launch” in the Application Guide for the detail.
To avoid the implicit ‘run’ command by AppleScript, put a ‘launch’ command for the application as suggested in the AppleScript Language Guide.
| * | Per documentation by Apple Computer, the ‘open application’ event tells the application that it has just been launched and so on. That would be the purpose of this Apple event. As for tasks really necessary to initialize the application, it is to be done immediately after the application is launched rather than in handling the ‘open application’ event. |
Open
When QuoEdit receives an ‘open’ command and opens the specified file, it remembers the file as a recent file like a case of executing the Open menu command. But if the opening by script means that the opening task is automated, it may be unnecessary to remember that file. In that case, add “without remembering” to the ‘open’ command as the parameter.
Print
Shifting parameter
If the line width is over the printable area, you can shift the contents horizontally to print out the remaining part.
You can also specify the vertical direction. But note that the header position cannot move to upper direction.
And note that the footer position never moves to the either direction.
Lines parameter
You can specify lines to be printed in each page. Note that determining the lines number is your responsibility. You can get the default lines under the current condition by ‘lines per page’ property of the document (document props).
Get
Get command for application
In AppleScript, the ‘get’ command functions as an AppleScript command or an application command. If the object whose data is to be returned belongs to an application, the ‘get’ command is sent to the application.
For example, suppose you are getting the first word in the first paragraph in the front document of QuoEdit by the following script.
tell application "QuoEdit"
get paragraph 1 of document 1
get word 1 of result
end tell
The first ‘get’ command is exactly sent to QuoEdit and it returns the result as string.
But note that the second ‘get’ command is handled by AppleScript even if it is put inside the ‘tell’ statements to QuoEdit because the value of the variable ‘result’ is just a string.
In many cases, that is no problem. But note that AppleScript may return incorrect string if you are editing text of foreign script (language) system. For example, Japanese script system determines word boundary in very different way from Roman script system. You can avoid that problem by letting the application get the word directly like the following.
tell application "QuoEdit"
get word 1 of paragraph 1 of document 1
end tell
QuoEdit gets the word properly considering the script (language) system of the document.
‘As’ parameter
When you specify ‘as’ parameter, there can be 2 scenarios about the coercion. One is that QuoEdit coerces the original data type to the requested type. Another is that QuoEdit returns the data without the coercion and AppleScript tries the coercion. The result in the later case occasionally depends on the system environment.
QuoEdit internally supports the following coercion.
|
Default data type |
|
Destination data type |
|
|
| string from contents of document |
| reference |
| string |
| styled text |
| string |
| international text |
| reference to text |
| string |
| reference to text |
| styled text |
| reference to text |
| international text |
| list as value of clipboard |
| string |
| list as value of clipboard |
| styled text (if the style info is contained) |
| string as a font name |
| number as the font id |
| alias |
| file specification |
| script |
| string * |
| script |
| styled text * |
| script |
| international text * |
| anything as script execution result |
| anything * |
|
For example, the following script is a variation of an example above.
tell application "QuoEdit"
get paragraph 1 of document 1 as styled text
get word 1 of result
end tell
As a styled text is passed to the second ‘get’ command in this case, now AppleScript can get the desired word properly with the proper script (language) system.
| * | Depends on the scripting component. |
Set
In AppleScript, the ‘set’ command functions as an AppleScript command or an application command. Like the ‘get’ command described above, the ‘set’ command is sent to an application if the object whose data is to be set belongs to the application.
But unlike AppleScript, QuoEdit does not return result value for the ‘set’ command*.
| * | Actually in Apple event definitions by Apple Computer, ‘set’ event is not defined to return the result (except the error). |
Count
In AppleScript, the ‘count’ command functions as an AppleScript command or an application command. If the object whose elements are to be counted belongs to an application, the ‘count’ command is sent to the application.
For example, suppose you are getting count of words in first paragraph in the front document by the following script.
tell application "QuoEdit"
get paragraph 1 of document 1
count word of result
end tell
In this case, note that the second command ‘count’ is handled by AppleScript even if it is put inside the ‘tell’ statements to QuoEdit because the value of the variable ‘result’ is just a string.
In many cases, that is no problem. But note that AppleScript may return incorrect result if you are editing text of foreign script (language) system. You can avoid that problem by letting the application count the words directly like the following.
tell application "QuoEdit"
count word of paragraph 1 of document 1
end tell
QuoEdit counts words properly considering the script (language) system of the document.
Of course, you can also avoid that problem of script (language) system by letting AppleScript count the styled text like the following.
tell application "QuoEdit"
get paragraph 1 of document 1 as styled text
count word of result
end tell
By the way, a statement “number of ...” is a variation of the ‘count’ command statement in AppleScript. That is, the term ‘number’ is not a property of something but generates a ‘count’ command. Note that you cannot use the statement “number of ...” to specify condition in the filter reference. For example:
tell document 1 of application "QuoEdit"
get index of every paragraph where 1 < number of lines
-- This reference is invalid!
end tell
In this case, you can use a property named ‘how many ...’ like the following.
tell document 1 of application "QuoEdit"
get index of every paragraph where 1 < how many lines
end tell
Data size
In QuoEdit, ‘data size’ command works only for byte length of plain text (that contains no style information nor other information)*. Note that even if you specify a document or the window as the object, QuoEdit returns the byte length of the text included in the document window.
You can also use ‘data size’ command to get data size of text in the Clipboard. Just specify ‘clipboard’ property of the application but never forget to activate QuoEdit.
tell application "QuoEdit"
activate
data size of clipboard
end tell
| * | The behavior described here is lazy one in QuoEdit. Apple event ‘data size’ is originally supposed to support various kinds of data size. |
Make
Makes a new element according to the specified parameters. The word “new” is optional in AppleScript.
Initial data for document
When you create a document object, you can specify initial data for the contents.
tell application "QuoEdit"
make new document with data initialData
end tell
Here, the initialData is a variable and can be data of any type if it can be text. In most cases, QuoEdit tries to get the value as string.
But there are two special cases in QuoEdit about the initial data, that is, when the initial data is a script object or ‘execution result’ property of application.
First, if you specify a script object as the initial data, QuoEdit makes a document window to edit the script. (The feature to edit scripts with QuoEdit is described later in this guide.)
tell application "QuoEdit"
load script (choose file)
make new document with data result
end tell
Second, if you specify the ‘execution result’ property, QuoEdit makes a usual document window with the text that expresses the result of last executed script.
tell application "QuoEdit"
make new document with data execution result
end tell
Note that in this case, QuoEdit once gets the text to display the result value from the scripting component (usually AppleScript) so that the data is not as is. For example, if the value of ‘execution result’ was a string, quotation marks are to be added. If you don’t wish that, write the script with two steps like the following.
tell application "QuoEdit"
get execution result
make new document with data result
end tell
Save
In QuoEdit, the following objects are supported by the ‘save’ command:
| ◊ | document (window) |
| ◊ | script |
| ◊ | text object in the document |
| ◊ | attachment of menu item if the value type is script object |
If the object has not been saved ever and if you didn’t specify the file to be saved, the save dialog box is to be shown. In this case, QuoEdit usually comes to front automatically (in version 0.71 and later) but the notation may be invoked if it could not be front. So, putting ‘activate’ statement before ‘save’ statement is recommended.
‘Remembering’ parameter has the sense only when saving ordinary document (document whose ‘edit type’ is text) with the ‘in’ parameter specifying a new file.
You can specify whether or not to save information of font, tab, line wrapping and so on by ‘saving resources’ parameter. But if the creator signature of the file is not one of QuoEdit ("QEdt"), the existing resources in the file are not removed even if you specified false for the ‘saving resources’ parameter. And the ‘saving resources’ parameter has no sense for documents for script (document whose ‘edit type’ is script).
Cut / Do copy / Paste
Activating
Before letting QuoEdit do these actions by script, activate QuoEdit first because cutting, copying or pasting in background will be failed. Note that QuoEdit does not check whether it is frontmost or background.
Do copy
Actually works as ‘copy’ command. All the function of the ‘copy’ command in QuoEdit is to copy the selected text to the CLIPBOARD. (That means, it does not work as ‘duplicate’ command that is not supported in QuoEdit.)
The original edition of “AppleScript Language Guide” defined that “the Copy command can function as an AppleScript command or an application command”. And as the functions of the application command, it described that it makes a copy of object(s) and put it in new location or on the Clipboard.
In the revised edition of “AppleScript Language Guide” (For AppleScript 1.3.7, May 1999 —> download), however, using ‘copy’ command as the application command is discouraged.
Therefore, to copy the selection to the Clipboard, using ‘do copy’ is recommended in QuoEdit rather than ‘copy’.
Especially, if you add the optional parameter (‘styl’ or ‘ignoring nurse’) to the ‘copy’ command, AppleScript will not accept the parameter at the compiling (though already compiled scripts have no problem). In this case, you have to use the term ‘do copy’.
Ignoring nurse parameter of Cut and Do copy commands
While operations are recorded, QuoEdit adds this parameter to Cut and Do Copy commands and “nurse” is an abbreviation of “no-user-selection error”.
Conventionally, if you try to cut or copy with no text selected, no-user-selection error (number -10013) is to be returned. But you will realize how it’s helpful to ignore the error when you treat tab delimited data and some fields are empty, for example.
Do script
Direct parameter
In QuoEdit, ‘do script’ command runs scripts supported by the OSA.
For the direct parameter, you can specify reference(s) to the following.
| ◊ | file or alias in which a compiled script is saved |
| ◊ | script object (index 1 or -1) of QuoEdit application |
| ◊ | script object (index 1) of a document |
| ◊ | menu item or attachment of the menu item, if the menu item’s kind is ‘running script’ and the attachment is not a reference to a folder |
On the other hand, it does not support data of script objects and text data of script sources (that don’t belong to anything). To run them, use the ‘run script’ command of the standard scripting additions.
To execute a script of the source text that is written in the document, once compile it with ‘compile’ command. The ‘compile’ command returns the reference to the compiled script that is like “script 1 of document 1”. Now you can run it by the ‘do script’ command.
If a menu item or the attachment is specified as the direct parameter and the script is changed after the execution, the change is saved automatically in the file; in the script file if the attachment is a reference to the file or in the menu definition file if the attachment is a script object data.
Memory keeping parameter
If a reference to script file is specified as the direct parameter, ‘do script’ command keeps the loaded script on memory by default. That is called the “last script” in this application and actually described so in scripts.
But to avoid the complication, it is rather recommended to specify false to the ‘memory keeping’ parameter when you write the ‘do script’ statements.
While operations are being recorded, QuoEdit automatically adds this parameter with the value of false when you do Execute Script menu command.
The ‘memory keeping’ parameter has a sense only if a reference to script file is specified as the direct parameter
Insert
Insert command is intended to be used to insert file contents into document and it is equivalent of doing Insert File menu command of the application.
insert alias "disk name:folder name:file name"
You can specify not only 'TEXT' file but also any kind of file as the direct parameter.
Though string (or text object) can be also specified as the direct parameter, currently it is not recommended. That is because if drag-and-drop operation is supported by the ‘insertion’ command in the future, intelligent cut and paste is to be applied so that the script can be incompatible.
For example, currently the results of following three statements are same. But using the standard command ‘set’ or ‘make’ is recommended rather than ‘insert’ command.
insert "new words" -- insert command
set contents of selection to "new words" -- set command
make text with data "new words" -- make command
QuoEdit will not apply the intelligent cut and paste feature to the both ‘set’ and ‘make’ command. It does not affect even result of “make word...” statement whether intelligent cut and paste is on or off.
Find / Search
In QuoEdit, ‘find’ command corresponds to the menu commands of Find Forward Again and Find Backward Again that search only front document starting at the current selection.
On the other hand, ‘search’ command corresponds to the menu command of Search Object and is intended to do more flexible search than the menu command. For example, it can search not only files or folders, but also documents or text objects in the document.
However, when you omitted all parameters for ‘search’ command, it behaves the same way as ‘find’ command except that ‘search’ command returns 1 or 0 (integer) while ‘find’ command returns true or false (boolean) as the result.
About ‘finding each one’ parameter of ‘search’ command
When applet or droplet sent ‘search’ event to QuoEdit with “finding each one” parameter and if many hit files were opened as a result, it could be unstable so that this optional parameter is not recommended.
Instead, “finding all first” parameter (that is a variation of “finding all”) is recommended to search for one hit per every file.
Do key
Like ‘jump to’ command, this is not like AppleScript command and writing script with it is not recommended so much. But this command (as well as ‘jump to’ command) is still very important to record and replay your task sequences.
Changed behavior of a parameter
In the old versions of QuoEdit, shortcut keys to move caret from tab to tab had been [Command+Tab] and [Command+Option+Tab]. But now they are [Control+Tab] and [Control+Option+Tab] since version 0.44, because [Command+Tab] is now used by Mac OS 8.5 and later to switch applications.
As for the ‘do key’ command, the followings are examples to move caret to the next tab stop or the previous tab.
Old:
do key _tab with {_cmd} or do key _tab with {_cmd, _option}
New:
do key _tab with {_ctrl} or do key _tab with {_ctrl, _option}
The point is that you should now use ‘_ctrl’ instead of ‘_cmd’. (Same thing even if ‘_shift’ was added respectively.)
Fortunately, ‘do key’ event is a high-level event, that means, it never generates actual key down so that the old statements that specify [Command+Tab] are still received by QuoEdit. But if you keep the old scripts in use (including recorded task sequences), renewing them is recommended.
Transliterate
Converts characters to the specified kind. When QuoEdit receives this event, it simply uses a function inside the Mac OS called “TransliterateText”, then replaces the specified text with the function result text.
Parameters
As for the direct parameter, only a reference to text object(s) in the document is available. Note that QuoEdit does not check the length of the specified text though the max text length that the TransliterateText function can treat is 65535 bytes (in my test).
Followings are constants for the parameters that specify original text kinds and destination text kind.
| For all script systems: |
| Roman |
| Roman text |
| native |
| text native to current script |
| For all 2-byte scripts: |
| Roman1 |
| 1-byte Roman text corresponding to Roman2 |
| Roman2 |
| 2-byte Roman text corresponding to Roman1 |
| For Japanese: |
| Katakana1 |
| 1-byte Katakana text |
| Katakana |
| 2-byte Katakana text |
| Hiragana |
| 2-byte Hiragana text |
| For Korean: |
| Hangul |
| 2-byte Hangul text |
| Jamo |
| 2-byte Jamo text |
| For traditional Chinese: |
| Bopomofo |
| 2-byte Zhuyinfuhao text |
Bugs
Bug of 1-byte <—> 2-byte conversion
Currently, conversion of 1-byte <—> 2-byte conversion in Chinese and Korean text (and for space characters in Japanese text in the older systems) are not perfect. It is probably problem of resources used by the TransliterateText function. A bug report on this issue was submitted to Apple Computer (requesting patch program).
Bug of Jamo <—> Hangul conversion
In newer systems,
Jamo —> Hangul conversion results in absolutely wrong characters
Hangul —> Jamo conversion results in infinite loop
while older systems with the Korean Language Kit never had such a problem (as long as I remember). A bug report on this issue was submitted to Apple Computer.
On the other hand, conversions of Roman <—> Jamo have no problem.
You cannot do conversion of Hangul <—> Roman directly. That is a designed behavior rather than a bug.
Compile
Compiles source text as a executable script and returns a reference to the compiled script object.
It can compile just text in a document. Whether the text is partial or entire, the result value is to be in format of ‘script 1 of document ...’. The compiled script is available until the contents of the document is modified (edited) again.
It is no matter whether the edit type of the document is ‘text’ or ‘script’. If it is the first time to compile text from ‘text’ editing document, the current scripting component by which your task sequence is recorded, usually AppleScript, is to be used.
Get props
To get a Record or List of properties of an object, usually you can write statements like the followings for example.
-- to get a record of the properties
{bounds: bounds, font: font, size: size} of document 1
-- to get a list of the properties
{bounds, font, size} of document 1
But in these cases, three times of Get events are generated by AppleScript, that is the number of the desired properties. (See the event log.)
Here, ‘get props’ command is designed to do that with just one Apple event. Call it like the followings (if you wish to make the script faster even slightly).
-- to get a record of the properties
get props of document 1 about {bounds:0, font:0, size:0}
-- to get a list of the properties
get props of document 1 about {bounds:0, font:0, size:0} as list
Note that each data (0 in the example) in the ‘about’ parameter is ignored:
about {bounds:0, font:0, size:0}
To eliminate the unnecessary data, you can also put a list of 4-character identifiers for the properties like the following.
about {"pbnd", "font", "ptsz"}
The identifiers are listed in a file “Raw Identifiers of Props” included in QuoEdit’s archive.
On the other hand, to set plural properties of an object with one Apple event, use a property named “properties”.
Hard wrap
Wraps the specified text object adding return characters by the specified line length.
You can specify only reference (including list of references) to text object in the document. Typically, you use this command like the following.
tell document 1 of application "QuoEdit"
hard wrap selection with length 72 with removing trailings
end tell
Note that the ‘with length’ parameter does not count the length of trailing space characters whether or not to remove them.
As a specific behavior of ‘hard wrap’ command, it adds return character at the beginning, the end or the both of the text object if there isn’t return character at that side.
Using that behavior(, this is a tip), you can hard wrap a text object by the every visible line like the following.
tell document 1 of application "QuoEdit"
hard wrap every line of selection with length 10000 with removing trailings
end tell
Tag
First removes tags specified by the ‘removing’ parameter from the both sides of the specified text object(s) if found. Then Adds the tags specified by the ‘with data’ parameter to the both sides of the specified text object(s).
Each string (tag) to remove or add is limited to 255 byte length without warning.
Use like the following if you need to remove nothing.
tag selection of document 1 with data {"<H1>", "</H1>"}
Of course you can do the same thing with ‘set’ command like the following. But in this case, an Apple event ‘get’ is once generated for the text of the selection.
set selection of document 1 to "<H1>" & selection of document 1 & "</H1>"
A parameter ‘each paragraph’, by which the tag command does the action for each paragraph of the target text, adds something special behavior. Without this parameter, of course you can write like the following, for example, to add tags to each paragraph of the selection.
tag every paragraph of selection of document 1 with data {"", "<BR>"}
In this case, naturally the action is to be done within the selection. And note that if the selection ends with a return character, the last paragraph of the selection exists at the top of the next paragraph as an empty string (= insertion point). So the ending tag "<BR>" is to be added to the beginning of the next paragraph.
Then, how about the following for the same purpose?
tag selection of document 1 with data {"", "<BR>"} with each paragraph
In this case (that ‘true’ is specified for the ‘each paragraph’ parameter), the action is done at every paragraph in which the selection is included. That means, if the selection is a part of the paragraph, the object is once extended to the whole paragraph and also the following return character if there is. And if the object ends with a return character, the last paragraph (the first insertion point of the next paragraph) is ignored. (What a convenient parameter!)
Note that when ‘true’ is specified for the ‘each paragraph’ parameter, you can specify only single object as the direct parameter for the ‘tag’ command.
Direct parameter of Cut, Do copy and Replace commands
As the direct parameter of ‘cut’, ‘do copy’ and ‘replace’ commands, QuoEdit does not accept document class object while it optionally accepts reference to text object. (The parameter for ‘replace’ command is supported in version 0.64 and later.)
For example, suppose that you are cutting the selection in the front document. The following statements will however result in the error.
tell document 1 of application "QuoEdit"
activate
cut
end tell
Execute it and see the event log. And you will see that the ‘cut’ event is actually sent as “cut document 1”.
To avoid the error in this case (if you don’t wish to remove the ‘tell’ statement to the document 1), write the ‘cut’ statement like one of the following.
tell application "QuoEdit" to cut
or
cut selection
On the other hand, in the case of commands like ‘paste’ and ‘undo’ (and ‘replace’ in the old versions) that never use the direct parameter, it seems that AppleScript eliminates the direct parameter at the compiling even if you specified it explicitly. (See the event log again about the behavior.) If QuoEdit actually received Apple event with the unknown parameter, it will return error.
‘At’ parameter of Make, Paste and Insert commands
To specify location at which new text is inserted by ‘make’, ‘paste’ and ‘insert’ commands, you typically use ‘at’ parameter specifying the text object to be replaced, sometimes insertion point or sometimes a range of text. In this case, the specified location is to be selected in the document before new text is inserted, but without activating the document if it is not front.
make characters with data "new words" at end of document 2
Currently, you can also specify a ‘document’ object to the ‘at’ parameter for the same purpose above, though not recommended.
make characters with data "new words" at document 2
In this case, QuoEdit interprets the location as the selection in the specified document. Please note that this interpretation is NOT compatible with the “Scriptable Text Editor” (STE), a sample application by Apple Computer, as it interprets the location as the entire contents of the document in this case.
It is recommended to specify the explicit location like the followings rather than the ‘document’ object (at least for QuoEdit).
make characters with data "new words" at selection of document 2
make characters with data "new words" at every text of document 2
Commands of application AeFile
QuoEdit is currently distributed with a scriptable application “AeFile” that supports two commands, that is, ‘let me choose’ and ‘let me make’ commands.*
The ‘let me choose’ command corresponds to the standard osax commands ‘choose file’ and ‘choose folder’. And the ‘let me make’ command corresponds to the ‘new file’ osax command though not completely compatible. The benefit to use the AeFile is that you can specify initial location to be viewed in the dialog boxes.
As the AeFile automatically becomes front (or notation is to be generated) when called and quits after done, you usually don’t have to describe ‘activate’ and ‘quit’ statements.
Like QuoEdit, the AeFile issues ‘open’ event or ‘reveal’ event to the Finder if you pressed the default button with Option key or Option+Shift keys. In that case, the AeFile returns user-canceled error, equivalent to cancel button pressed, whose error number is -128.**
You can use the AeFIle freely with other applications. If you are software developer, feel free to make your program communicate with the AeFile. For example, another included utility “QuoEdit's Menu” communicates with the AeFile via Apple event to select a file or folder.
| * | The ‘let me choose’ command had been once supported by QuoEdit (in the development) as ‘choose one file’ command. The AeFile is a result of separation of the command from QuoEdit. |
| ** | It also returns the usual result (programmatically, with keyAEResult parameter) in the version 1.1 and later. It seems that AppleScript cannot retrieve it, though. |
Table of contents